<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::session::App Struct Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Public API.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1session.html">session</a></li><li class="navelem"><a class="el" href="structipc_1_1session_1_1App.html">App</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-types">Public Types</a> &#124;
<a href="#pub-attribs">Public Attributes</a> &#124;
<a href="#related">Related Functions</a> &#124;
<a href="structipc_1_1session_1_1App-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::session::App Struct Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A <em>description</em> of an application in this <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> inter-process communication universe.  
 <a href="structipc_1_1session_1_1App.html#details">More...</a></p>

<p><code>#include &lt;app.hpp&gt;</code></p>
<div class="dynheader">
Inheritance diagram for ipc::session::App:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="structipc_1_1session_1_1App__inherit__graph.svg" width="347" height="107"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-types" name="pub-types"></a>
Public Types</h2></td></tr>
<tr class="memitem:af7527bc1ad0cde62cd4fde97bc1d7ecc"><td class="memItemLeft" align="right" valign="top"><a id="af7527bc1ad0cde62cd4fde97bc1d7ecc" name="af7527bc1ad0cde62cd4fde97bc1d7ecc"></a>
using&#160;</td><td class="memItemRight" valign="bottom"><b>Master_set</b> = boost::unordered_map&lt; std::string, <a class="el" href="structipc_1_1session_1_1App.html">App</a> &gt;</td></tr>
<tr class="memdesc:af7527bc1ad0cde62cd4fde97bc1d7ecc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Suggested type for storing master repository or all <code>Apps</code>s. See <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> doc header for discussion. <br /></td></tr>
<tr class="separator:af7527bc1ad0cde62cd4fde97bc1d7ecc"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-attribs" name="pub-attribs"></a>
Public Attributes</h2></td></tr>
<tr class="memitem:a8e67b57829fe43a122a23c699b5de8fd"><td class="memItemLeft" align="right" valign="top">std::string&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd">m_name</a></td></tr>
<tr class="memdesc:a8e67b57829fe43a122a23c699b5de8fd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Brief application name, readable to humans and unique across all other applications' names; used both as a short programmatic key in shared resource naming (including as a folder in <a class="el" href="namespaceipc_1_1session.html#a6d07d9996af19e57eb42416e914110ea" title="Convenience alias for the commonly used type util::Shared_name.">Shared_name</a> for kernel-persistent resources and addresses; and in path names &ndash; such as PID file name &ndash; in the file system).  <a href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd">More...</a><br /></td></tr>
<tr class="separator:a8e67b57829fe43a122a23c699b5de8fd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae82a8635858664720c8546e468f8090b"><td class="memItemLeft" align="right" valign="top">fs::path&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structipc_1_1session_1_1App.html#ae82a8635858664720c8546e468f8090b">m_exec_path</a></td></tr>
<tr class="memdesc:ae82a8635858664720c8546e468f8090b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Absolute, lexically normalized canonical path to the executable entity (which is not a directory), as it would appear in a command line or <code>exec()</code>-like invocation when actually invoking the application.  <a href="structipc_1_1session_1_1App.html#ae82a8635858664720c8546e468f8090b">More...</a><br /></td></tr>
<tr class="separator:ae82a8635858664720c8546e468f8090b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9e32297579603f2d96616976474d0246"><td class="memItemLeft" align="right" valign="top"><a id="a9e32297579603f2d96616976474d0246" name="a9e32297579603f2d96616976474d0246"></a>
<a class="el" href="namespaceipc_1_1util.html#a6435c1b48ec8684c24ca406d1d17208e">util::user_id_t</a>&#160;</td><td class="memItemRight" valign="bottom"><b>m_user_id</b></td></tr>
<tr class="memdesc:a9e32297579603f2d96616976474d0246"><td class="mdescLeft">&#160;</td><td class="mdescRight">The application must run as this user ID (UID). Files and other shared resources shall have this owner. <br /></td></tr>
<tr class="separator:a9e32297579603f2d96616976474d0246"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a78bb1e984835f429fd44869a83f4b093"><td class="memItemLeft" align="right" valign="top"><a id="a78bb1e984835f429fd44869a83f4b093" name="a78bb1e984835f429fd44869a83f4b093"></a>
<a class="el" href="namespaceipc_1_1util.html#a3f7d069ce0d23f73153da2e2559dc3d3">util::group_id_t</a>&#160;</td><td class="memItemRight" valign="bottom"><b>m_group_id</b></td></tr>
<tr class="memdesc:a78bb1e984835f429fd44869a83f4b093"><td class="mdescLeft">&#160;</td><td class="mdescRight">The application must run as this group ID (GID). Files and other shared resources shall have this owner. <br /></td></tr>
<tr class="separator:a78bb1e984835f429fd44869a83f4b093"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="related" name="related"></a>
Related Functions</h2></td></tr>
<tr><td class="ititle" colspan="2"><p >(Note that these are not member functions.) </p>
</td></tr>
<tr class="memitem:a6b2f9a90ac9cc5098d9b90e7f547c97e"><td class="memItemLeft" align="right" valign="top">std::ostream &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structipc_1_1session_1_1App.html#a6b2f9a90ac9cc5098d9b90e7f547c97e">operator&lt;&lt;</a> (std::ostream &amp;os, const <a class="el" href="structipc_1_1session_1_1App.html">App</a> &amp;val)</td></tr>
<tr class="memdesc:a6b2f9a90ac9cc5098d9b90e7f547c97e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Prints string representation of the given <code><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a></code> to the given <code>ostream</code>.  <a href="structipc_1_1session_1_1App.html#a6b2f9a90ac9cc5098d9b90e7f547c97e">More...</a><br /></td></tr>
<tr class="separator:a6b2f9a90ac9cc5098d9b90e7f547c97e"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A <em>description</em> of an application in this <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> inter-process communication universe. </p>
<p >An application is, at least roughly speaking, 1-1 with a distinct executable presumably interested in communicating with another such executable. A process is an instance of an application that has begun execution at some point.</p>
<p >An <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> is a <em>description</em> of an application, and typically used (at least after program initialization, before actual IPC begins) only as supertype of <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> and/or <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a>, it is possible that 2+ <code><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a></code>s exist but describe one actual application but in different roles. 2+ such <code><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a></code>s must have all members equal to each other respectively. In particular see <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">App::m_name</a>.</p>
<p >This is a data store (and a simple one). The same holds of <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> and <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a>. As of this writing there are no rigid rules as to the existence of an App/Client_app/Server_app with this or that stored inside. Make them all day long, if you want! More restrictions shall come into play only when passing various <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> objects and sub-objects (in some form) to <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> APIs, most notably the <a class="el" href="classipc_1_1session_1_1Session.html" title="A documentation-only concept defining the local side of an IPC conversation (session) with another en...">Session</a> concept and buddies.</p>
<p >However, to be useful, we suggest the following convention. Some key <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a> APIs may rely on it.</p>
<h3><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a>, <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a>, <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a> registry conventions</h3>
<ul>
<li>Maintain a global (to the applications in your IPC universe) registry of known applications. It could be stored in JSON or XML form in some central shared software component and read-into a master <code>set</code> or <code>unordered_set</code> (by <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">App::m_name</a>; see its doc header) available in a centrally-available library; or this <code>*set</code> could simply be a hard-coded C++ <code>extern const</code>; whatever works.</li>
<li>In the current model supported by <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>: Suppose app Ap wants to communicate with app Bp; this is called the A-B <em>split</em>. In any A-B split, one must be chosen as the <em>client</em>, the other as the <em>server</em>; let's by convention here assume they're always listed in server-client order. However, it is allowed that two splits A-B and C-A co-exist in the same universe; meaning A is server when speaking to B but client when speaking to C. Lastly, for each server app X, there is a global list of distinct client apps that are allowed to initiate IPC sessions with it (see ipc::Session concept). Given that:<ul>
<li>An <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> (in the above-described global registry) that is a client in any split shall be copied-into a (separate) <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> object.<ul>
<li>This global registry of known client applications shall similarly be maintained as a global <code>*set</code>. (The information regarding which apps are clients, too, can be read from JSON/XML/whatever or hard-coded.)</li>
</ul>
</li>
<li>Similarly an <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> that is a server in any split shall be copied-into a (separate) <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a> object, forming the 3rd and final global <code>*set</code> of applications.<ul>
<li>For each such <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a>, save the Client::m_name of each <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> allowed to initiate sessions with it into its <a class="el" href="structipc_1_1session_1_1Server__app.html#a12df649b33893270afeac7240a571633" title="A given Client_app (as identified by its distinct App::m_name) may request to establish an IPC sessio...">Server_app::m_allowed_client_apps</a>. (Again, this mapping can be read from JSON/XML/whatever or be hard-coded in some fashion. In the end, though, it would go into <code>m_allowed_client_apps</code>.)</li>
</ul>
</li>
</ul>
</li>
</ul>
<p >Thus one would end up with, after initialization of each process wishing to participate in a given IPC universe:</p><ul>
<li>An immutable <code>*set</code> of <code><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a></code>s (global <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> registry).</li>
<li>An immutable <code>*set</code> of <code><a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a></code>s (global <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a> registry).</li>
<li>An immutable <code>*set</code> of <code><a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a></code>s (global <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a> registry), each <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a> listing the <code>m_name</code>s of <code><a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a></code>s referring to the applications that may initiate sessions with it in its immutable <a class="el" href="structipc_1_1session_1_1Server__app.html#a12df649b33893270afeac7240a571633" title="A given Client_app (as identified by its distinct App::m_name) may request to establish an IPC sessio...">Server_app::m_allowed_client_apps</a>.</li>
</ul>
<p >There should be no need, from this moment on, to copy any <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a>, <a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a>, or <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a>. It shall be passed by <code>const</code> reference. </p>
</div><h2 class="groupheader">Friends And Related Function Documentation</h2>
<a id="a6b2f9a90ac9cc5098d9b90e7f547c97e" name="a6b2f9a90ac9cc5098d9b90e7f547c97e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a6b2f9a90ac9cc5098d9b90e7f547c97e">&#9670;&nbsp;</a></span>operator&lt;&lt;()</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">std::ostream &amp; operator&lt;&lt; </td>
          <td>(</td>
          <td class="paramtype">std::ostream &amp;&#160;</td>
          <td class="paramname"><em>os</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="structipc_1_1session_1_1App.html">App</a> &amp;&#160;</td>
          <td class="paramname"><em>val</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">related</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Prints string representation of the given <code><a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a></code> to the given <code>ostream</code>. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">os</td><td>Stream to which to write. </td></tr>
    <tr><td class="paramname">val</td><td>Object to serialize. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>os</code>. </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Data Documentation</h2>
<a id="ae82a8635858664720c8546e468f8090b" name="ae82a8635858664720c8546e468f8090b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae82a8635858664720c8546e468f8090b">&#9670;&nbsp;</a></span>m_exec_path</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">fs::path ipc::session::App::m_exec_path</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Absolute, lexically normalized canonical path to the executable entity (which is not a directory), as it would appear in a command line or <code>exec()</code>-like invocation when actually invoking the application. </p>
<p >Formally (refer to cppreference.com <code>filesystem::path</code> doc page):</p><ul>
<li>There is no root-name: No Windows drive letters ("C:"), no network file share ("//share_name"), etc.</li>
<li>It is a Unix path: Only forward-slash is used as separator, and that character always is a separator.</li>
<li>It is absolute: It starts with forward-slash.</li>
<li>It is lexically normalized: See reference, but essentially it means no more than one slash in a row, no dot components, no dot-dot components. (Note: dots and dot-dots can <em>appear</em> &ndash; but an <em>entire</em> component cannot comprise solely such a sequence; where component means: a thing preceded by slash and succeeded by slash or end-of-path.)</li>
</ul>
<p >Do note that because of the "as it would appear in a command line..." requirement this indirectly restricts how processes are to be invoked in this system: always via 1, absolute, lexically normal path to the executable. (Do also note this is still not necessary force an unambiguous way to invoke an application installed at a given location: sym-links, at least, introduce an infinite number of ways to refer to the same binary. That said, at least lexical normalization can be done programmatically in <code>fs</code>, and sym-link following path resolution is also separately supplied by <code>fs</code>.) </p>

</div>
</div>
<a id="a8e67b57829fe43a122a23c699b5de8fd" name="a8e67b57829fe43a122a23c699b5de8fd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8e67b57829fe43a122a23c699b5de8fd">&#9670;&nbsp;</a></span>m_name</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">std::string ipc::session::App::m_name</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Brief application name, readable to humans and unique across all other applications' names; used both as a short programmatic key in shared resource naming (including as a folder in <a class="el" href="namespaceipc_1_1session.html#a6d07d9996af19e57eb42416e914110ea" title="Convenience alias for the commonly used type util::Shared_name.">Shared_name</a> for kernel-persistent resources and addresses; and in path names &ndash; such as PID file name &ndash; in the file system). </p>
<h3>Convention: mandated use as key</h3>
<p >Neither <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> nor any nearby sub-class or alias of <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> (<a class="el" href="structipc_1_1session_1_1Client__app.html" title="An App that is used as a client in at least one client-server IPC split.">Client_app</a>, <a class="el" href="structipc_1_1session_1_1Server__app.html" title="An App that is used as a server in at least one client-server IPC split.">Server_app</a>) shall be used as the key type in an associative container (e.g., <code>set</code>, <code>unordered_map</code>). Instead <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">App::m_name</a> shall be used as the key when lookup by distinct application is desired. Two scenarios come to mind:</p><ul>
<li>You want to store a set of applications fitting some criterion/a, but this is not some master repository of <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> objects in the first place &ndash; rather it is referring to some subset of such a master repository.<ul>
<li>Then, store simply a <code>set</code> or <code>unordered_set</code> (etc.) of <code>std::string m_name</code>s.<ul>
<li>Rationale: The basic desired operation here is an exitence-check (is application X present, based on some definition of present?). <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> is by definition guaranteed to be distinct from all others. Hence storing such strings alone is sufficient and reasonably efficient while also not relying on <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> address uniqueness for lookup (which, while efficient, is a pain to maintain).</li>
</ul>
</li>
</ul>
</li>
<li>You want to store some master repository of <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> objects, with all their config such as UID, GID, etc.<ul>
<li>Then, store a <code>map</code> or <code>unordered_map</code>, with the keys being <code>std::string m_name</code>s, while the values are filled-out <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> objects (or objects of <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> sub-class) &ndash; with the guarantee that <code>M[name].m_name == name</code> for all <code>name</code>s in any such <code>M</code>.<ul>
<li>Rationale: Same as above; but in addition to being able to perform existence-check by <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a>, one can also iterate through the master details of all the applications and/or lookup a given application's master details.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p >Due to these conventions:</p><ul>
<li>We do not supply the usual complement of associative-container "stuff" for <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> and buddies: equality, less-than, hashing. We do not want to encourage direct <a class="el" href="structipc_1_1session_1_1App.html" title="A description of an application in this ipc::session inter-process communication universe.">App</a> storage that way.</li>
<li>The idea is: When such storage is desired, use that usual complement of associative-container "stuff" that is already supplied for <code>std::string</code>, as applied to <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">App::m_name</a>.</li>
</ul>
<p >Digression regarding rationale: Why use <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a>, and not (say) <code>const App*</code>, as the key in associative lookups? Answer: It was considered. Due to the infrequency of such lookups, combined with the debug-friendliness/expressiveness of referring to a distinct app by its user-readable name, the lookup-by-name convention felt more straightforward and convenient. Plus, the address of an object stored in a container may change while it is being built, which would add an element of brittleness. One could also use an iterator as a key, but then the registry container would be mandated to be iteratator-stable-under-insertion, and that brings an annoying host of worries. Indexing by string name is solid by comparison, if a bit slower.</p>
<h3>Conventions: Naming</h3>
<p >Must begin with an ASCII alphabetical character and otherwise consist of only ASCII alphanumerics and underscores. While these are partially conventions driven by style (for example, dashes could also be allowed &ndash; we just do not want them to be, so that underscores are always the word-separator used consistently), the following is an important guarantee for related <a class="el" href="namespaceipc_1_1session.html#a6d07d9996af19e57eb42416e914110ea" title="Convenience alias for the commonly used type util::Shared_name.">Shared_name</a> and <code>fs::path</code> semantics:</p><ul>
<li>Must not contain a <a class="el" href="classipc_1_1util_1_1Shared__name.html#a5c0910497c5ec484d3e42dfb0ccad48d" title="Character we use, by convention, to separate conceptual folders within str().">util::Shared_name::S_SEPARATOR</a>.</li>
<li>Must not contain a forward-slash or any other file system path separator.</li>
<li>Must not contain a dot or any other conceivable extension separator (other than underscore).</li>
</ul>
<p >Therefore:</p><ul>
<li>In <a class="el" href="namespaceipc_1_1session.html#a6d07d9996af19e57eb42416e914110ea" title="Convenience alias for the commonly used type util::Shared_name.">Shared_name</a> paths one can embed <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> by preceding and/or succeeding it with a <a class="el" href="classipc_1_1util_1_1Shared__name.html#a5c0910497c5ec484d3e42dfb0ccad48d" title="Character we use, by convention, to separate conceptual folders within str().">util::Shared_name::S_SEPARATOR</a>, thus making it a full or partial folder name.</li>
<li>In file system paths one can embed <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> by preceding and/or succeeding it with a forward-slash, thus making it a full or partial directory name.</li>
<li>In either: one can embed <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> by preceding and/or succeeding it with a dot as an extension separator.</li>
</ul>
<p >So if <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> is "abc_def" one can do things like "/some/dir/abc_def/some_file" and "/some/dir/abc_def.pid/file" and "/some/dir/prefix.abc_def.3". I.e., <a class="el" href="structipc_1_1session_1_1App.html#a8e67b57829fe43a122a23c699b5de8fd" title="Brief application name, readable to humans and unique across all other applications&#39; names; used both...">m_name</a> can be safely used as a conceptual "token," even when combined with path/name separators and dot-extension naming. </p>

</div>
</div>
<hr/>The documentation for this struct was generated from the following files:<ul>
<li>session/<a class="el" href="app_8hpp.html">app.hpp</a></li>
<li>session/<a class="el" href="session__fwd_8hpp.html">session_fwd.hpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 11 2025 20:02:23 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
